---

This section details on the original issue you should resolve

<issue_title>[plan] Add package-level documentation to core packages</issue_title>
<issue_description>## Objective

Add comprehensive package-level documentation comments to major packages for better API discoverability and developer onboarding.

Context

From discussion githubnext/gh-aw#12006: Sergo analysis found missing package-level documentation across 5+ major packages. Go convention requires // Package X comments for proper pkg.go.dev presentation and go doc output.

Packages to Document

Priority order:

1. pkg/workflow/ - Core compilation logic (600+ files, most critical)
2. pkg/types/ - Type definitions
3. pkg/cli/ - CLI interface
4. pkg/parser/ - Markdown/YAML parsing
5. pkg/logger/ - Logging utilities

Documentation Requirements

Each package doc should include:

• Purpose: What the package does
• Key concepts: Main abstractions and terminology
• Basic usage: Simple code example
• Architecture: How components fit together
• Links: Related packages or documentation

Example Template

// Package workflow provides compilation and generation of GitHub Actions workflows
// from markdown-based agentic workflow specifications.
//
// The workflow package is the core of gh-aw, handling the transformation of
// user-friendly markdown files into production-ready GitHub Actions YAML workflows.
// It supports advanced features including:
//   - Agentic AI workflow execution with Claude, Codex, and Copilot engines
//   - Safe output handling with configurable permissions
//   - MCP (Model Context Protocol) server integration
//   - Network sandboxing and firewall configuration
//
// # Basic Usage
//
//     compiler := workflow.NewCompiler(workflow.CompilerOptions{
//         Verbose: true,
//     })
//     err := compiler.CompileWorkflow("path/to/workflow.md")
//
// # Architecture
//
// The compilation process consists of:
//  1. Frontmatter parsing (YAML metadata extraction)
//  2. Markdown processing (prompt extraction)
//  3. Tool configuration (MCP servers, safe outputs)
//  4. Job generation (main, activation, safe output jobs)
//  5. YAML generation (final GitHub Actions workflow)
package workflow

Acceptance Criteria

• All 5 packages have comprehensive package-level docs
• Documentation includes purpose, usage example, and architecture overview
• go doc pkg/workflow produces readable output
• pkg.go.dev presentation is clear and professional
• Code examples compile without errors

AI generated by Plan Command for discussion #12006

Comments on the Issue (you are @copilot in this section)